---
target: Umo Office Convert
keywords: Umo Office Convert,office在线预览,wps在线预览,docx在线预览,word在线预览,pdf在线预览
description: 将 Office、WPS 等 40 余种办公文档转换为可在线查看的文档格式，可与 Umo Office Viewer 结合使用实现办公文档的在线预览。
---

# Webhook 回调通知说明

当文件上传或转换完成后，服务可向配置的 Webhook 地址发送通知，便于业务系统接收并触发后续流程。通过环境变量 `CONVERTED_WEBHOOK_URL` 开启。

## 触发时机

- 文档上传成功后发送一次通知
- 文档成功转换后发送一次通知
- 若命中缓存（同文件哈希），也会发送通知（标识 `fromCache=true`）

## 回调请求

- 方法：`POST`
- 头信息：`Content-Type: application/json`
- 目标：`CONVERTED_WEBHOOK_URL`

## 负载示例

```json
{
  "taskId": "bccbff66-fa2c-4d6d-bc30-a7c34ca0181b",
  "type": "uploaded",
  "fromCache": false,
  "file": {
    "filename": "测试文档.docx",
    "mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "size": 90239,
    "path": "/uploads/2024/10/bccbff66-fa2c-4d6d-bc30-a7c34ca0181b.docx"
  }
}
```

字段说明：
- `taskId`: 转换任务 ID，用于后续查询原始文件或结果文件。
- `type`: 事件类型，目前为 `uploaded`。
- `fromCache`: 是否从缓存返回的结果。
- `file`: 文件的元信息。

## 安全建议

- 使用 HTTPS Webhook 地址。
- 配置 IP 白名单或签名校验（如 HMAC），签名可在请求头或负载中携带。

## 与下载接口协同

- 收到回调后，业务可使用接口 `GET /convert/{taskId}` 下载文件。
